FMOD API User Manual 2.02

7. Core API Reference | SoundGroup

An interface that manages Sound Groups

Group Functions:

Sound Functions:

General:

FMOD_SOUNDGROUP_BEHAVIOR

Values specifying behavior when a sound group's max audible value is exceeded.

C
C++
C#
JS

typedef enum FMOD_SOUNDGROUP_BEHAVIOR {
  FMOD_SOUNDGROUP_BEHAVIOR_FAIL,
  FMOD_SOUNDGROUP_BEHAVIOR_MUTE,
  FMOD_SOUNDGROUP_BEHAVIOR_STEALLOWEST,
  FMOD_SOUNDGROUP_BEHAVIOR_MAX
} FMOD_SOUNDGROUP_BEHAVIOR;

enum SOUNDGROUP_BEHAVIOR
{
    BEHAVIOR_FAIL,
    BEHAVIOR_MUTE,
    BEHAVIOR_STEALLOWEST,
    MAX,
}

FMOD.SOUNDGROUP_BEHAVIOR_FAIL
FMOD.SOUNDGROUP_BEHAVIOR_MUTE
FMOD.SOUNDGROUP_BEHAVIOR_STEALLOWEST
FMOD.SOUNDGROUP_BEHAVIOR_MAX
FMOD_SOUNDGROUP_BEHAVIOR_FAIL
Excess sounds will fail when calling System::playSound.
FMOD_SOUNDGROUP_BEHAVIOR_MUTE
Excess sounds will begin mute and will become audible when sufficient sounds are stopped.
FMOD_SOUNDGROUP_BEHAVIOR_STEALLOWEST
Excess sounds will steal from the quietest Sound playing in the group.
FMOD_SOUNDGROUP_BEHAVIOR_MAX
Maximum number of SoundGroup behaviors.

When using FMOD_SOUNDGROUP_BEHAVIOR_MUTE, SoundGroup::setMuteFadeSpeed can be used to stop a sudden transition.
Instead, the time specified will be used to cross fade between the sounds that go silent and the ones that become audible.

See Also: SoundGroup::setMaxAudibleBehavior, SoundGroup::getMaxAudibleBehavior, SoundGroup::setMaxAudible, SoundGroup::getMaxAudible, SoundGroup::setMuteFadeSpeed, SoundGroup::getMuteFadeSpeed

SoundGroup::getMaxAudible

Retrieves the maximum number of playbacks to be audible at once in a sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getMaxAudible(
  int *maxaudible
);

FMOD_RESULT FMOD_SoundGroup_GetMaxAudible(
  FMOD_SOUNDGROUP *soundgroup,
  int *maxaudible
);

RESULT SoundGroup.getMaxAudible(
  out int maxaudible
);

SoundGroup.getMaxAudible(
  maxaudible
);
maxaudible Out

Maximum number of playbacks to be audible at once.

  • Range: [-1, inf)
  • Default: -1

See Also: SoundGroup::setMaxAudible

SoundGroup::getMaxAudibleBehavior

Retrieves the current max audible behavior.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getMaxAudibleBehavior(
  FMOD_SOUNDGROUP_BEHAVIOR *behavior
);

FMOD_RESULT FMOD_SoundGroup_GetMaxAudibleBehavior(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SOUNDGROUP_BEHAVIOR *behavior
);

RESULT SoundGroup.getMaxAudibleBehavior(
  out SOUNDGROUP_BEHAVIOR behavior
);

SoundGroup.getMaxAudibleBehavior(
  behavior
);
behavior Out

SoundGroup max playbacks behavior. (FMOD_SOUNDGROUP_BEHAVIOR)

See Also: SoundGroup::setMaxAudibleBehavior

SoundGroup::getMuteFadeSpeed

Retrieves the current mute fade time.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getMuteFadeSpeed(
  float *speed
);

FMOD_RESULT FMOD_SoundGroup_GetMuteFadeSpeed(
  FMOD_SOUNDGROUP *soundgroup,
  float *speed
);

RESULT SoundGroup.getMuteFadeSpeed(
  out float speed
);

SoundGroup.getMuteFadeSpeed(
  speed
);
speed Out

Fade time. 0 = no fading.

  • Units: Seconds
  • Range: [0, inf)
  • Default: 0

See Also: SoundGroup::setMuteFadeSpeed

SoundGroup::getName

Retrieves the name of the sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getName(
  char *name,
  int namelen
);

FMOD_RESULT FMOD_SoundGroup_GetName(
  FMOD_SOUNDGROUP *soundgroup,
  char *name,
  int namelen
);

RESULT SoundGroup.getName(
  out string name,
  int namelen
);

SoundGroup.getName(
  name
);
name Out
Name of the SoundGroup. (UTF-8 string)
namelen

Length of name.

  • Units: Bytes

See Also: System::createSoundGroup

SoundGroup::getNumPlaying

Retrieves the number of currently playing channels for the sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getNumPlaying(
  int *numplaying
);

FMOD_RESULT FMOD_SoundGroup_GetNumPlaying(
  FMOD_SOUNDGROUP *soundgroup,
  int *numplaying
);

RESULT SoundGroup.getNumPlaying(
  out int numplaying
);

SoundGroup.getNumPlaying(
  numplaying
);
numplaying Out
Number of actively playing Channels from sounds in this SoundGroup.

This routine returns the number of Channels playing. If the SoundGroup only has one Sound, and that Sound is playing twice, the figure returned will be two.

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::getNumSounds

Retrieves the current number of sounds in this sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getNumSounds(
  int *numsounds
);

FMOD_RESULT FMOD_SoundGroup_GetNumSounds(
  FMOD_SOUNDGROUP *soundgroup,
  int *numsounds
);

RESULT SoundGroup.getNumSounds(
  out int numsounds
);

SoundGroup.getNumSounds(
  numsounds
);
numsounds Out
Number of Sounds in this SoundGroup.

See Also: SoundGroup::getSound

SoundGroup::getSound

Retrieves a sound.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getSound(
  int index,
  Sound **sound
);

FMOD_RESULT FMOD_SoundGroup_GetSound(
  FMOD_SOUNDGROUP *soundgroup,
  int index,
  FMOD_SOUND **sound
);

RESULT SoundGroup.getSound(
  int index,
  out Sound sound
);

SoundGroup.getSound(
  index,
  sound
);
index
Index of the sound.
sound Out
Sound object. (Sound)

Use SoundGroup::getNumSounds in conjunction with this function to enumerate all sounds in a SoundGroup.

See Also: System::createSound

SoundGroup::getSystemObject

Retrieves the parent System object.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getSystemObject(
  System **system
);

FMOD_RESULT FMOD_SoundGroup_GetSystemObject(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SYSTEM **system
);

RESULT SoundGroup.getSystemObject(
  out System system
);

SoundGroup.getSystemObject(
  system
);
system Out
System object. (System)

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::getUserData

Retrieves a user value associated with this object.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getUserData(
  void **userdata
);

FMOD_RESULT FMOD_SoundGroup_GetUserData(
  FMOD_SOUNDGROUP *soundgroup,
  void **userdata
);

RESULT SoundGroup.getUserData(
  out IntPtr userdata
);

SoundGroup.getUserData(
  userdata
);
userdata Out
Value stored on this object.

See Also: SoundGroup::setUserData

SoundGroup::getVolume

Retrieves the volume of the sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::getVolume(
  float *volume
);

FMOD_RESULT FMOD_SoundGroup_GetVolume(
  FMOD_SOUNDGROUP *soundgroup,
  float *volume
);

RESULT SoundGroup.getVolume(
  out float volume
);

SoundGroup.getVolume(
  volume
);
volume Out

Volume level.

  • Units: Linear
  • Range: [0, 1]
  • Default: 1

See Also: SoundGroup::setVolume

SoundGroup::release

Releases a soundgroup object and returns all sounds back to the master sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::release();

FMOD_RESULT FMOD_SoundGroup_Release(FMOD_SOUNDGROUP *soundgroup);

RESULT SoundGroup.release();

SoundGroup.release();

You cannot release the master SoundGroup.

See Also: System::createSoundGroup, System::getMasterSoundGroup

SoundGroup::setMaxAudible

Sets the maximum number of playbacks to be audible at once in a sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::setMaxAudible(
  int maxaudible
);

FMOD_RESULT FMOD_SoundGroup_SetMaxAudible(
  FMOD_SOUNDGROUP *soundgroup,
  int maxaudible
);

RESULT SoundGroup.setMaxAudible(
  int maxaudible
);

SoundGroup.setMaxAudible(
  maxaudible
);
maxaudible

Maximum number of playbacks to be audible at once. -1 denotes unlimited.

  • Range: [-1, inf)
  • Default: -1

If playing instances of sounds in this group equal or exceed number specified here, attepts to play more of the sounds with be met with FMOD_ERR_MAXAUDIBLE by default.
Use SoundGroup::setMaxAudibleBehavior to change the way the sound playback behaves when too many sounds are playing. Muting, failing and stealing behaviors can be specified. See FMOD_SOUNDGROUP_BEHAVIOR.

SoundGroup::getNumPlaying can be used to determine how many instances of the sounds in the SoundGroup are currently playing.

See Also: SoundGroup::getMaxAudible, SoundGroup::setMaxAudibleBehavior, SoundGroup::getMaxAudibleBehavior

SoundGroup::setMaxAudibleBehavior

This function changes the way the sound playback behaves when too many sounds are playing in a soundgroup.

C
C++
C#
JS

FMOD_RESULT SoundGroup::setMaxAudibleBehavior(
  FMOD_SOUNDGROUP_BEHAVIOR behavior
);

FMOD_RESULT FMOD_SoundGroup_SetMaxAudibleBehavior(
  FMOD_SOUNDGROUP *soundgroup,
  FMOD_SOUNDGROUP_BEHAVIOR behavior
);

RESULT SoundGroup.setMaxAudibleBehavior(
  SOUNDGROUP_BEHAVIOR behavior
);

SoundGroup.setMaxAudibleBehavior(
  behavior
);
behavior

SoundGroup max playbacks behavior. (FMOD_SOUNDGROUP_BEHAVIOR)

See Also: SoundGroup::getMaxAudibleBehavior, SoundGroup::setMaxAudible, SoundGroup::getMaxAudible

SoundGroup::setMuteFadeSpeed

Sets a mute fade time.

C
C++
C#
JS

FMOD_RESULT SoundGroup::setMuteFadeSpeed(
  float speed
);

FMOD_RESULT FMOD_SoundGroup_SetMuteFadeSpeed(
  FMOD_SOUNDGROUP *soundgroup,
  float speed
);

RESULT SoundGroup.setMuteFadeSpeed(
  float speed
);

SoundGroup.setMuteFadeSpeed(
  speed
);
speed

Fade time. 0 = no fading.

  • Units: Seconds
  • Range: [0, inf)
  • Default: 0

If a mode besides FMOD_SOUNDGROUP_BEHAVIOR_MUTE is used, the fade speed is ignored.

When more sounds are playing in a SoundGroup than are specified with SoundGroup::setMaxAudible, the least important Sound (ie lowest priority / lowest audible volume due to 3D position, volume etc) will fade to silence if FMOD_SOUNDGROUP_BEHAVIOR_MUTE is used, and any previous sounds that were silent because of this rule will fade in if they are more important.

See Also: SoundGroup::getMuteFadeSpeed

SoundGroup::setUserData

Sets a user value associated with this object.

C
C++
C#
JS

FMOD_RESULT SoundGroup::setUserData(
  void *userdata
);

FMOD_RESULT FMOD_SoundGroup_SetUserData(
  FMOD_SOUNDGROUP *soundgroup,
  void *userdata
);

RESULT SoundGroup.setUserData(
  IntPtr userdata
);

SoundGroup.setUserData(
  userdata
);
userdata
Value stored on this object.

Associates some data with this object to give it context, it will be passed back via callbacks but otherwise remain untouched.

See Also: SoundGroup::getUserData

SoundGroup::setVolume

Sets the volume of the sound group.

C
C++
C#
JS

FMOD_RESULT SoundGroup::setVolume(
  float volume
);

FMOD_RESULT FMOD_SoundGroup_SetVolume(
  FMOD_SOUNDGROUP *soundgroup,
  float volume
);

RESULT SoundGroup.setVolume(
  float volume
);

SoundGroup.setVolume(
  volume
);
volume

Volume level.

  • Units: Linear
  • Range: [0, 1]
  • Default: 1

Scales the volume of all Channels playing Sounds in this SoundGroup.

See Also: SoundGroup::getVolume

SoundGroup::stop

Stops all sounds within this soundgroup.

C
C++
C#
JS

FMOD_RESULT SoundGroup::stop();

FMOD_RESULT FMOD_SoundGroup_Stop(FMOD_SOUNDGROUP *soundgroup);

RESULT SoundGroup.stop();

SoundGroup.stop();

See Also: System::playSound

FMOD API User Manual 2.02.05 (2021-12-20). © 2021 Firelight Technologies Pty Ltd.